<!DOCTYPE html>
<!--
     SPDX-License-Identifier: CC-BY-SA-4.0
     SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
-->
<!-- Page last generated 2025-02-20 03:16:15 +0000 -->
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>libsel4vm_guest_memory | seL4 docs</title>

    <!-- Our stylesheet and theme stylesheet.  Contains bootstrap. -->
    <link rel="stylesheet" href="/assets/css/style.css" type="text/css">
    <!-- Font awesome -->
    <link href="https://use.fontawesome.com/releases/v5.0.8/css/all.css" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
    <!-- Pygments syntax highlighting  -->
    <link rel="stylesheet" href="/assets/css/highlighting/trac.css" type="text/css">
    <link rel="icon" type="image/x-icon" href="/assets/favicon.ico"><script defer data-domain="docs.sel4.systems"
	    src="https://analytics.sel4.systems/js/script.js"></script></head>

  <body class="container-fluid">

    



<header>
  <ul class="row menu">
    <li class="col-xs-12 col-md-2" >
            <a href="https://sel4.systems" class="skip-icon">
              <img class="img-responsive" src="/assets/logo-text-white.svg" alt="seL4 logo" />
            </a>
    </li>
    <li class="col-xs-12 col-md-10 menu">
      <nav aria-label="Banner links">
        <h2><a href="/Resources" />Resources</h2>
        <h2><a href="/processes" />Contributing</a></h2>
        <h2><a href="/projects" />Projects</h2>
        <h2><a href="/Tutorials" />Tutorials</h2>
        <iframe title="DuckDuckGo search bar" src="https://duckduckgo.com/search.html?site=docs.sel4.systems&prefill=Search%20sel4.systems" style="overflow:hidden;margin-bottom:10px; padding:0;height:40px;float:right;border-width: 0px"></iframe>
      </nav>
    </li>
  </ul>
  <div class="clear"></div>
  
<div class="breadcrumbs bootstrap hidden-sm-down">
  <nav class="sel-breadcrumb" aria-label="Breadcrumb" >
    <ol class=" list-unstyled" vocab="http://schema.org/" typeof="BreadcrumbList">
      
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/">
              <span property="name"><b>seL4 Docs</b></span>
            </a>
            <meta property="position" content="1" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/projects/">
              <span property="name"><b>Projects</b></span>
            </a>
            <meta property="position" content="2" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/projects/virtualization/">
              <span property="name"><b>Virtualisation on seL4</b></span>
            </a>
            <meta property="position" content="3" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/projects/virtualization/docs/">
              <span property="name"><b>libsel4vm & libsel4vmmplatsupport API documentation</b></span>
            </a>
            <meta property="position" content="4" />
        </li>
      
        

        
          <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <span property="name">libsel4vm_guest_memory</span>
            <meta property="position" content="5" /></li>
          
    </ol>
  </nav>
  <nav class="sel-version" aria-label="Current Versions">
    <ol class="list-unstyled">
      <li class="list-unstyled text-right" style="margin-left:auto; padding:0rem 0rem;">
        Current versions:</li>
      <li class="list-unstyled text-right">
      <a href="/releases/sel4/13.0.0"><b>seL4-13.0.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/microkit/1.4.1"><b>microkit-1.4.1</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/camkes/camkes-3.11.0"><b>camkes-3.11.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/capdl/0.3.0"><b>capDL-0.3.0</b></a></li>
      </ol>
  </nav>
  <div class='clear'></div>
</div>


</header>

    <main>
      <div class="row">
  <div class="hidden-xs col-sm-4 col-md-3 col-lg-2">
    


<div class="sidebar">















    <ul class="nav nav-sidebar">
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4/">seL4</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/l4v/">L4.verified</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/camkes/">CAmkES</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/capdl/">CapDL</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/elfloader/">Elfloader</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/buildsystem/">seL4 Buildsystem</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/user_libs/">user_libs</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4runtime/">The seL4 run-time</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4webserver/">seL4webserver</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4-tutorials/">seL4 tutorials</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4bench/">sel4bench</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4test/">seL4Test</a>
        </li>
  
    
    

    
        <li class="active">
            <a class="" href="/projects/virtualization/">Virtualization</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/camkes-vm/">camkes-vm</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/dockerfiles/">Dockerfiles</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/docsite/">seL4 Documentation website</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/sel4_tools/">seL4_tools</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/microkit/">Microkit</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/hardware_hacks/">Hardware Hacks</a>
        </li>
  
    
    

    
        <li class="">
            <a class="" href="/projects/rust/">Rust</a>
        </li>
  
    </ul>


</div>

  </div>
  <div class="content col-sm-8 col-md-6 col-lg-7 main">
    <!--
     Copyright 2020, Data61, CSIRO (ABN 41 687 119 230)

     SPDX-License-Identifier: CC-BY-SA-4.0
-->

<h2 id="interface-guest_memoryh">Interface <code class="language-plaintext highlighter-rouge">guest_memory.h</code></h2>

<p>The libsel4vm memory interface provides useful abstractions to manage your guest VM’s address space.
This interface can be leveraged for uses such as mapping device memory into your VM instance
or for creating emulated device regions binded with custom handlers/callbacks.
The main mechanisms this interface provides involves reserving memory regions and using those reservations
to either map memory into your guest VM’s address space or emulate subsequent accesses. Reservations
are created through either using <code class="language-plaintext highlighter-rouge">vm_reserve_memory_at</code> or <code class="language-plaintext highlighter-rouge">vm_reserve_anon_memory</code>.
The user can then further back the reservation with seL4 frames by performing <code class="language-plaintext highlighter-rouge">vm_map_reservation</code>.</p>

<h3 id="brief-content">Brief content:</h3>

<p><strong>Functions</strong>:</p>

<blockquote>
  <p><a href="#function-vm_reserve_memory_atvm-addr-size-fault_callback-cookie"><code class="language-plaintext highlighter-rouge">vm_reserve_memory_at(vm, addr, size, fault_callback, cookie)</code></a></p>
</blockquote>

<blockquote>
  <p><a href="#function-vm_reserve_anon_memoryvm-size-fault_callback-cookie-addr"><code class="language-plaintext highlighter-rouge">vm_reserve_anon_memory(vm, size, fault_callback, cookie, addr)</code></a></p>
</blockquote>

<blockquote>
  <p><a href="#function-vm_free_reserved_memoryvm-reservation"><code class="language-plaintext highlighter-rouge">vm_free_reserved_memory(vm, reservation)</code></a></p>
</blockquote>

<blockquote>
  <p><a href="#function-vm_map_reservationvm-reservation-map_iterator-cookie"><code class="language-plaintext highlighter-rouge">vm_map_reservation(vm, reservation, map_iterator, cookie)</code></a></p>
</blockquote>

<blockquote>
  <p><a href="#function-vm_map_reservationvm-reservation-frames-num_frames-frame_size_bits"><code class="language-plaintext highlighter-rouge">vm_map_reservation_frames(vm, reservation, frames, num_frames, frame_size_bits)</code></a></p>
</blockquote>

<blockquote>
  <p><a href="#function-vm_get_reservation_memory_regionreservation-addr-size"><code class="language-plaintext highlighter-rouge">vm_get_reservation_memory_region(reservation, addr, size)</code></a></p>
</blockquote>

<blockquote>
  <p><a href="#function-vm_memory_initvm"><code class="language-plaintext highlighter-rouge">vm_memory_init(vm)</code></a></p>
</blockquote>

<p><strong>Structs</strong>:</p>

<blockquote>
  <p><a href="#struct-vm_frame_t"><code class="language-plaintext highlighter-rouge">vm_frame_t</code></a></p>
</blockquote>

<h2 id="functions">Functions</h2>

<p>The interface <code class="language-plaintext highlighter-rouge">guest_memory.h</code> defines the following functions.</p>

<h3 id="function-vm_reserve_memory_atvm-addr-size-fault_callback-cookie">Function <code class="language-plaintext highlighter-rouge">vm_reserve_memory_at(vm, addr, size, fault_callback, cookie)</code></h3>

<p>Reserve a region of the VM’s memory at a given base address</p>

<p><strong>Parameters:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">vm {vm_t *}</code>: A handle to the VM</li>
  <li><code class="language-plaintext highlighter-rouge">addr {uintptr}</code>: Base address of the memory region being reserved</li>
  <li><code class="language-plaintext highlighter-rouge">size {size_t}</code>: Size of the memory region being reserved</li>
  <li><code class="language-plaintext highlighter-rouge">fault_callback {memory_fault_callback_fn}</code>: Callback function that will be invoked if memory region is faulted on</li>
  <li><code class="language-plaintext highlighter-rouge">cookie {void *}</code>: User cookie to pass onto to callback</li>
</ul>

<p><strong>Returns:</strong></p>

<ul>
  <li>NULL on failure otherwise a pointer to a reservation object representing the reserved region</li>
</ul>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<h3 id="function-vm_reserve_anon_memoryvm-size-align-fault_callback-cookie-addr">Function <code class="language-plaintext highlighter-rouge">vm_reserve_anon_memory(vm, size, align, fault_callback, cookie, addr)</code></h3>

<p>Reserve an anonymous region of the VM’s memory. This uses memory previously made anonymous
through the <code class="language-plaintext highlighter-rouge">vm_memory_make_anon</code> function.</p>

<p><strong>Parameters:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">vm {vm_t *}</code>: A handle to the VM</li>
  <li><code class="language-plaintext highlighter-rouge">size {size_t}</code>: Size of the anoymous emory region being reserved</li>
  <li><code class="language-plaintext highlighter-rouge">align {size_t}</code>: Requested alignment of the memory region</li>
  <li><code class="language-plaintext highlighter-rouge">fault_callback {memory_fault_callback_fn}</code>: Callback function that will be invoked if memory region is faulted on</li>
  <li><code class="language-plaintext highlighter-rouge">cookie {void *}</code>: User cookie to pass onto to callback</li>
  <li><code class="language-plaintext highlighter-rouge">addr {uintptr_t *}</code>: Pointer that will be set with the base address of the reserved anonymous region</li>
</ul>

<p><strong>Returns:</strong></p>

<ul>
  <li>NULL on failure otherwise a pointer to a reservation object representing the reserved region</li>
</ul>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<h3 id="function-vm_free_reserved_memoryvm-reservation">Function <code class="language-plaintext highlighter-rouge">vm_free_reserved_memory(vm, reservation)</code></h3>

<p>Free memory reservation from the VM</p>

<p><strong>Parameters:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">vm {vm_t *}</code>: A handle to the VM</li>
  <li><code class="language-plaintext highlighter-rouge">reservation {vm_memory_reservation_t *}</code>: Pointer to the reservation being free’d</li>
</ul>

<p><strong>Returns:</strong></p>

<ul>
  <li>-1 on failure otherwise 0 for success</li>
</ul>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<h3 id="function-vm_map_reservationvm-reservation-map_iterator-cookie">Function <code class="language-plaintext highlighter-rouge">vm_map_reservation(vm, reservation, map_iterator, cookie)</code></h3>

<p>Map a reservation into the VM’s virtual address space</p>

<p><strong>Parameters:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">vm {vm_t *}</code>: A handle to the VM</li>
  <li><code class="language-plaintext highlighter-rouge">reservation {vm_memory_reservation_t *}</code>: Pointer to reservation object being mapped</li>
  <li><code class="language-plaintext highlighter-rouge">map_iterator {memory_map_iterator_fn}</code>: Iterator function that returns a cap to the memory region being mapped</li>
  <li><code class="language-plaintext highlighter-rouge">cookie {void *}</code>: Cookie to pass onto map_iterator function</li>
</ul>

<p><strong>Returns:</strong></p>

<ul>
  <li>-1 on failure otherwise 0 for success</li>
</ul>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<h3 id="function-vm_map_reservation_framesvm-reservation-frames-num_frames-frame_size_bits">Function <code class="language-plaintext highlighter-rouge">vm_map_reservation_frames(vm, reservation, frames, num_frames, frame_size_bits)</code></h3>

<p>Map a reservation into the VM’s virtual address space from given frames</p>

<p><strong>Parameters:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">vm {vm_t *}</code>: A handle to the VM</li>
  <li><code class="language-plaintext highlighter-rouge">reservation {vm_memory_reservation_t *}</code>: Pointer to reservation object being mapped</li>
  <li><code class="language-plaintext highlighter-rouge">frames {seL4_CPtr *}</code>: Array of frame caps</li>
  <li><code class="language-plaintext highlighter-rouge">num_frames {size_t}</code>: Number of frame caps</li>
  <li><code class="language-plaintext highlighter-rouge">frame_size_bits {size_t}</code>: Bit size of a single frame</li>
</ul>

<p><strong>Returns:</strong></p>

<ul>
  <li>-1 on failure otherwise 0 for success</li>
</ul>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<h3 id="function-vm_get_reservation_memory_regionreservation-addr-size">Function <code class="language-plaintext highlighter-rouge">vm_get_reservation_memory_region(reservation, addr, size)</code></h3>

<p>Get the memory region information (address &amp; size) from a given reservation</p>

<p><strong>Parameters:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">reservation {vm_memory_reservation_t *}</code>: Pointer to reservation object</li>
  <li><code class="language-plaintext highlighter-rouge">addr {uintptr_t *}</code>: Pointer that will be set with the address of reservation</li>
  <li><code class="language-plaintext highlighter-rouge">size {size_t *}</code>: Pointer that will be set with the size of reservation</li>
</ul>

<p><strong>Returns:</strong></p>

<p>No return</p>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<h3 id="function-vm_memory_initvm">Function <code class="language-plaintext highlighter-rouge">vm_memory_init(vm)</code></h3>

<p>Initialise a VM’s memory management interface</p>

<p><strong>Parameters:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">vm {vm_t *}</code>: A handle to the VM</li>
</ul>

<p><strong>Returns:</strong></p>

<ul>
  <li>-1 on failure otherwise 0 for success</li>
</ul>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<h2 id="structs">Structs</h2>

<p>The interface <code class="language-plaintext highlighter-rouge">guest_memory.h</code> defines the following structs.</p>

<h3 id="struct-vm_frame_t">Struct <code class="language-plaintext highlighter-rouge">vm_frame_t</code></h3>

<p>Structure representing a mappable memory frame</p>

<p><strong>Elements:</strong></p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">cptr {seL4_CPtr}</code>: Capability to frame</li>
  <li><code class="language-plaintext highlighter-rouge">rights {seL4_CapRights_t}</code>: Mapping rights of frame</li>
  <li><code class="language-plaintext highlighter-rouge">vaddr {uintptr_t}</code>: Virtual address of which to map the frame into</li>
  <li><code class="language-plaintext highlighter-rouge">size_bits {size_t}</code>: Size of frame in bits</li>
</ul>

<p>Back to <a href="#module-guest_memoryh">interface description</a>.</p>

<p>Back to <a href="#">top</a>.</p>


  </div>







  
  
<div class="sidebar-toc hidden-xs hidden-sm col-md-3 col-lg-3">
  
    <ul class="section-nav">
    	<h2> Virtualization </h2> 
        <li>
          
          <a style="" class="" href="/projects/virtualization/">
            Documentation homepage
          </a>
        </li>

















    
        <h3>Repositories</h3>
    
        <li>
          <a class="" href="https://github.com/seL4proj/seL4_projects_libs">
            seL4_projects_libs
          </a>
        </li>









  







    </ul>

</div>


</div>

    </main>
    


<footer class="site-footer">

  <h2 class="footer-heading">seL4 docs</h2>

  <div class="footer-col-wrapper">

    <div class="col-md-2">
      



<ul class="social-media-list">
  <li><a href="https://github.com/sel4"><i class="fab fa-github"></i> <span class="username">sel4</span></a></li><li><a href="https://github.com/sel4proj"><i class="fab fa-github"></i> <span class="username">sel4proj</span></a></li>
</ul>

    </div>

    <div class="col-md-8">
      <ul class="list-unstyled">
        <li>
          This site is for displaying seL4 related documentation.  Pull requests are welcome.
        </li>
        
          <li>
            Site last updated: Fri Feb 7 10:17:38 2025 +1100 ee78c8857c
          </li>
          <li>
                Page last updated: 
          </li>
        
      </ul>
    </div>
    <div class="col-md-2">
<a href="https://github.com/seL4/docs/blob/master/projects/virtualization/docs/api/libsel4vm_guest_memory.md">View page on GitHub</a>
      <br />
      <a href="https://github.com/seL4/docs/edit/master/projects/virtualization/docs/api/libsel4vm_guest_memory.md">Edit page on GitHub</a>
      <br />
      <a href="/sitemap">Sitemap</a>
    </div>

  </div>

</footer>

  </body>
</html>
